Causal Map 3 Functions

This file briefly illustrates the causal mapping functions for Causal Map 3.

The functions are used within Causal Map 3, which provides a web interface for managing causal mapping project and also enables autocoding with AI. The functions can also be used in the R console as illustrated here.

These functions completely replace the functions in the old R package CausalMapFunctions which is now deprecated. This new set of functions is much simpler.

Setup

Load the functions and some example data

Inspecting the example data file

ex$links %>% 
  arrange(desc(source_count)) %>% 
  select(from_label,to_label,source_count,source_id,link_id,statement_id) %>% 
  head
## # A tibble: 6 × 6
##   from_label                to_label source_count source_id link_id statement_id
##   <chr>                     <chr>           <dbl> <chr>       <dbl> <chr>       
## 1 Health behaviour; Use pi… Improve…           16 MNX-2         602 MNX-2 | 244 
## 2 Health behaviour; Use pi… Improve…           16 TWX-1         624 TWX-1 | 169 
## 3 Health behaviour; Use pi… Improve…           16 TWX-2         627 TWX-2 | 206 
## 4 Health behaviour; Use pi… Improve…           16 MSX-2         640 MSX-2 | 323 
## 5 Health behaviour; Use pi… Improve…           16 MSY-1         644 MSY-1 | 363 
## 6 Health behaviour; Use pi… Improve…           16 TWX-3         650 TWX-3 | 401
ex$links %>% 
  arrange(desc(source_count)) %>% 
  distinct(from_label,to_label,.keep_all = T) %>% 
  select(from_label,to_label,source_count,source_id,link_id,statement_id) %>% 
  head
## # A tibble: 6 × 6
##   from_label                to_label source_count source_id link_id statement_id
##   <chr>                     <chr>           <dbl> <chr>       <dbl> <chr>       
## 1 Health behaviour; Use pi… Improve…           16 MNX-2         602 MNX-2 | 244 
## 2 Community groups/learning Communi…           14 MNY-1          16 MNY-1 | 70  
## 3 Health behaviour; Use be… Improve…           14 MNX-2         601 MNX-2 | 244 
## 4 Health behaviour; Use mo… Improve…           14 MNX-2         603 MNX-2 | 244 
## 5 Farm production           Income             13 MNY-1          10 MNY-1 | 62  
## 6 Increased knowledge; Far… Planted…           13 TWX-1          20 TWX-1 | 88
ex$links %>% 
  make_factors_from_links() %>% 
  arrange(desc(source_count)) %>% 
  head
## # A tibble: 6 × 11
##   label        found found_source found_target source_count link_count in_degree
##   <chr>        <lgl> <lgl>        <lgl>               <int>      <int>     <int>
## 1 Improved he… FALSE FALSE        FALSE                  18        150         7
## 2 Diet improv… FALSE FALSE        FALSE                  17         51         7
## 3 Food consum… FALSE FALSE        FALSE                  17         37         6
## 4 Health beha… FALSE FALSE        FALSE                  17         19        16
## 5 Community g… FALSE FALSE        FALSE                  16         37        37
## 6 Farm produc… FALSE FALSE        FALSE                  16        158        81
## # ℹ 4 more variables: out_degree <int>, outcomeness <dbl>, flipped_from <int>,
## #   flipped_to <int>
ex$sources %>% 
  select(1:6) %>% 
  head
## # A tibble: 6 × 6
##   source_id `Household code` `#Name of province` `#Name of village`
##   <chr>     <chr>            <chr>               <chr>             
## 1 MNX-1     MNX1             A                   1                 
## 2 MNX-2     MNX2             A                   1                 
## 3 MNX-3     MNX3             A                   1                 
## 4 MNX-4     MNX4             A                   1                 
## 5 MNX-5     MNX5             A                   1                 
## 6 MNX-6     MNX6             A                   1                 
## # ℹ 2 more variables: `#Age of the main respondent` <chr>,
## #   `Household size (residents > 6months)` <chr>
ex$statements %>% 
  select(1:6) %>% 
  head
## # A tibble: 6 × 6
##   text                       source_id question_id created modified statement_id
##   <chr>                      <chr>     <chr>       <chr>   <chr>    <chr>       
## 1 This is a fully coded exa… MSY-3     $A8         2023-0… 2023-06… MSY-3 | 1   
## 2 There has been a lot of c… MSY-3     $B1         2023-0… 2023-06… MSY-3 | 2   
## 3 Improved                   MSY-3     $*B2        2023-0… 2023-06… MSY-3 | 3   
## 4 There has been improvemen… MSY-3     $B3         2023-0… 2023-06… MSY-3 | 4   
## 5 Yes there have been some … MSY-3     $C1         2023-0… 2023-06… MSY-3 | 5   
## 6 Increased                  MSY-3     $*C2        2023-0… 2023-06… MSY-3 | 6

All the transforms functions

Zoooming

ex$links %>% 
  make_factors_from_links() %>% 
  arrange(desc(source_count)) %>% 
  head
## # A tibble: 6 × 11
##   label        found found_source found_target source_count link_count in_degree
##   <chr>        <lgl> <lgl>        <lgl>               <int>      <int>     <int>
## 1 Improved he… FALSE FALSE        FALSE                  18        150         7
## 2 Diet improv… FALSE FALSE        FALSE                  17         51         7
## 3 Food consum… FALSE FALSE        FALSE                  17         37         6
## 4 Health beha… FALSE FALSE        FALSE                  17         19        16
## 5 Community g… FALSE FALSE        FALSE                  16         37        37
## 6 Farm produc… FALSE FALSE        FALSE                  16        158        81
## # ℹ 4 more variables: out_degree <int>, outcomeness <dbl>, flipped_from <int>,
## #   flipped_to <int>
ex$links %>% 
  pipe_zoom() %>%
  make_factors_from_links() %>% 
  arrange(desc(source_count)) %>% 
  head
## # A tibble: 6 × 11
##   label        found found_source found_target source_count link_count in_degree
##   <chr>        <lgl> <lgl>        <lgl>               <int>      <int>     <int>
## 1 Diet improv… FALSE FALSE        FALSE                  19        102        22
## 2 Health beha… FALSE FALSE        FALSE                  18        161       130
## 3 Improved he… FALSE FALSE        FALSE                  18        150         7
## 4 Increased k… FALSE FALSE        FALSE                  18        234       214
## 5 Food consum… FALSE FALSE        FALSE                  17         37         6
## 6 Community g… FALSE FALSE        FALSE                  16         37        37
## # ℹ 4 more variables: out_degree <int>, outcomeness <dbl>, flipped_from <int>,
## #   flipped_to <int>

Tracing paths

Tracing paths, showing source IDs

ex$links %>% 
  pipe_zoom() %>%
  pipe_trace(sess_links = ex$links,from_labels = "Farm production",to_labels="Diet improved",steps = 2,transforms_tracing_threads = F) %>%  
  pipe_label("source_id") %>% 
  make_print_map2(original = ex$links,map_color_factors_column = "outcomeness")

Tracing threads, showing source IDs

ex$links %>% 
  pipe_zoom() %>%
  pipe_trace(sess_links = ex$links,from_labels = "Farm production",to_labels="Diet improved",steps = 2,transforms_tracing_threads = T) %>%  
  pipe_label("source_id") %>% 
  make_print_map2(original = ex$links,map_label_factors = "source_count")

Tracing paths, showing source counts

ex$links %>% 
  pipe_zoom() %>%
  pipe_trace(sess_links = ex$links,from_labels = "Farm production",to_labels="Diet improved",steps = 2,transforms_tracing_threads = F) %>%  
  pipe_label("source_count") %>% 
  make_print_map2(original = ex$links,map_label_factors = "source_count")

Tracing threads, showing source counts

ex$links %>% 
  pipe_zoom() %>%
  pipe_trace(sess_links = ex$links,from_labels = "Farm production",to_labels="Diet improved",steps = 2,transforms_tracing_threads = T) %>%  
  pipe_label("source_count") %>% 
  make_print_map2(original = ex$links,map_label_factors = "source_count")

Tracing just one step

ex$links %>% 
  pipe_zoom() %>%
  pipe_trace(sess_links = ex$links,from_labels = "Farm production",to_labels="Diet improved",steps = 1) %>%  
  make_print_map2(original = ex$links)

Tracing threads, three steps

ex$links %>% 
  pipe_zoom() %>%
  pipe_trace(sess_links = ex$links,from_labels = "Farm production",to_labels="Diet improved",steps = 3,transforms_tracing_threads = T) %>%  
  pipe_label("link_count") %>% 
  make_print_map2(original = ex$links,map_label_factors = "source_count")

Removing brackets

This file doesn’t actually have factor names with brackets, but we can create some

tmp <- 
  ex$links %>% 
  mutate(from_label=str_replace_all(from_label,"Wellbeing","Wellbeing (outcome)")) %>% 
  mutate(to_label=str_replace_all(to_label,"Wellbeing","Wellbeing (outcome)"))

tmp %>% 
  pipe_zoom() %>%
  pipe_focus(c("Wellbeing"),any=T) %>%  
  pipe_top_factors(5) %>% 
  make_print_map2(original = ex$links,map_label_factors = "source_count")
tmp %>% 
  pipe_zoom() %>%
  pipe_focus(c("Wellbeing"),any=T) %>%  
  pipe_top_factors(5) %>% 
  pipe_remove_brackets(round = T) %>% 
  make_print_map2(original = ex$links,map_label_factors = "source_count")

Focus

ex$links %>% 
  pipe_zoom() %>%
  pipe_focus(c("Ability to buy food")) %>%  
  make_print_map2(original = ex$links,map_label_factors = "source_count")
ex$links %>% 
  pipe_zoom() %>%
  pipe_focus(c("Ability"),any = T) %>%  
  make_print_map2(original = ex$links,map_label_factors = "source_count")
ex$links %>% 
  pipe_zoom() %>%
  pipe_focus(c("Ability to buy food","Diet improved"),any = T) %>%  
  make_print_map2(original = ex$links,map_label_factors = "source_count")
ex$links %>% 
  pipe_zoom() %>%
  pipe_focus(c("Ability","Diet improved"),any = T) %>%  
  make_print_map2(original = ex$links,map_label_factors = "source_count")

Exclude

ex$links %>% 
  pipe_zoom() %>%
  pipe_top_factors(type="Links",which="Top",top=6) %>%
  select(from_label,to_label,link_count,source_count) %>% 
  distinct %>% 
  head
## # A tibble: 6 × 4
## # Groups:   from_label, to_label [6]
##   from_label          to_label            link_count source_count
##   <chr>               <chr>                    <int>        <int>
## 1 Increased knowledge Health behaviour            23            6
## 2 Farm production     Income                      32           13
## 3 Increased knowledge Increased knowledge          8            6
## 4 Increased knowledge Farm production             24           11
## 5 Increased knowledge Diet improved               30            8
## 6 Diet improved       Improved health              8            4
ex$links %>% 
  pipe_zoom() %>%
  pipe_top_factors(type="Links",which="Top",top=6) %>%
  pipe_exclude("Increased knowledge" %>% c("Diet improved")) %>% 
  select(from_label,to_label,link_count,source_count) %>% 
  distinct %>% 
  head
## # A tibble: 2 × 4
##   from_label       to_label        link_count source_count
##   <chr>            <chr>                <int>        <int>
## 1 Farm production  Income                  32           13
## 2 Health behaviour Improved health        128           18

Hashtags

ex$links %>% 
  pipe_zoom() %>%
  pipe_retain_hashtags(hashtags = "#hypothetical",keep=T)  %>% 
  select(from_label,to_label,link_count,source_count,hashtags) 
## # A tibble: 4 × 5
##   from_label          to_label                  link_count source_count hashtags
##   <chr>               <chr>                          <int>        <int> <chr>   
## 1 Increased knowledge Improved health                    1            1 #hypoth…
## 2 Organisation 1      Access to fertiliser               1            1 #hypoth…
## 3 Broken taboo        Diet improved                      1            1 #hypoth…
## 4 Increased knowledge Planted new crop/vegetab…          1            1 #hypoth…
ex$links %>% 
  pipe_zoom() %>%
  pipe_retain_hashtags(hashtags = "#hypothetical",keep=T)  %>% 
  pipe_label("hashtags") %>% 
  make_print_map2(ex$links)
ex$links %>% 
  pipe_zoom() %>%
  pipe_retain_hashtags(hashtags = "#hypothetical",keep=F)  %>% 
  filter(hashtags!="") %>% 
  select(from_label,to_label,link_count,source_count,hashtags) 
## # A tibble: 2 × 5
##   from_label                      to_label      link_count source_count hashtags
##   <chr>                           <chr>              <int>        <int> <chr>   
## 1 Improved/new farming techniques Farm product…         17           12 #hypoth…
## 2 Income                          Ability to b…         14           11 #hypoth…

Combining opposites

ex$links %>% 
  pipe_focus(xc("~"),any = T) %>% 
  pipe_top_factors(20) %>% 
  make_print_map2(ex$links)
ex$links %>% 
  pipe_focus(xc("~"),any = T) %>% 
  pipe_top_factors(20) %>% 
  make_print_map2(ex$links,map_colour_opposites_red = T)
ex$links %>% 
  pipe_focus(xc("~"),any = T) %>% 
  pipe_combine_opposites() %>% 
  pipe_top_factors(20) %>% 
  make_print_map2(ex$links)
if(F){
  ex2 <- get_file("opposites-example",conn=conn)
  
ex2$links %>% 
  pipe_combine_opposites() %>% 
  make_print_map2(ex$links)
  
  
}

Creating additional tables

Mentions table

ex$links %>% 
  make_mentions_tabl() %>% 
  select(label,direction,link_id)
## # A tibble: 3,228 × 3
##    label                                   direction   link_id
##    <chr>                                   <chr>         <dbl>
##  1 Health behaviour                        consequence       1
##  2 Income                                  consequence       3
##  3 Produced enough food to eat and/or sell consequence       4
##  4 Able to buy farming equipment/materials consequence       5
##  5 Ability to buy food                     consequence       6
##  6 Produced enough food to eat and/or sell consequence       7
##  7 Produced enough food to eat and/or sell consequence       8
##  8 Broken taboo                            consequence       9
##  9 Income                                  consequence      10
## 10 Increased ability to borrow             consequence      11
## # ℹ 3,218 more rows
ex$links %>% 
  make_mentions_tabl() %>% 
  select(label,direction,link_id) %>% 
  pivot_wider(names_from=direction,values_from = link_id,values_fn = length)
## # A tibble: 145 × 4
##    label                                       consequence influence either
##    <chr>                                             <int>     <int>  <int>
##  1 Health behaviour                                      6        15     21
##  2 Income                                               47        41     88
##  3 Produced enough food to eat and/or sell              11         9     20
##  4 Able to buy farming equipment/materials               6        NA      6
##  5 Ability to buy food                                  16        20     36
##  6 Broken taboo                                          7         8     15
##  7 Increased ability to borrow                           1         1      2
##  8 Increased ability to save/increased savings          23         9     32
##  9 Improved household relationships                     26         7     33
## 10 Shared household decision-making                     12         9     21
## # ℹ 135 more rows

Formatting the map

Note that labelling links is a pipe function, not part of the call to the map

ex$links %>% 
  pipe_zoom(1) %>% 
  pipe_top_factors(8) %>% 
  make_print_map2(ex$links,map_color_factors_column = "outcomeness")
ex$links %>% 
  pipe_zoom(1) %>% 
  pipe_top_factors(8) %>% 
  pipe_label("source_count") %>% 
  make_print_map2(ex$links,map_color_factors_column = "source_count",map_size_factors = "source_count",map_label_factors = "source_count",map_size_links = "source_count",map_wrap_factor_labels = 9)

Surprises

Calculating surprises is technically a formatting function

ex$links %>% 
  pipe_zoom(1) %>% 
  pipe_top_links(8) %>% 
  pipe_label(map_label_links = "#Name of village" ,type="Surprise_links") %>% 
  make_print_map2(original = ex$links,map_color_factors_column = "link_count",map_size_links ="link_count")
ex$links %>% 
  pipe_zoom(1) %>% 
  pipe_top_links(8) %>% 
  pipe_label(map_label_links = "#Name of village",type="Surprise_sources" ) %>% 
  make_print_map2(original = ex$links,map_color_factors_column = "link_count",map_size_links ="link_count")
ex$links %>% 
  pipe_zoom(1) %>% 
  pipe_top_links(18) %>% 
  pipe_label(map_label_links = "#Name of village",type = "Surprise_links" ) %>% 
  make_print_map2(original = ex$links,map_color_factors_column = "link_count",map_size_links ="source_count")